package com.dreamycode.paths;

import java.io.FileFilter;
import java.io.FilenameFilter;
import java.util.List;
import java.util.regex.Pattern;

/**
 * Represents only a folder NOT a file.
 * Provides all the handy methods of java.io.File (for a directory) and relates to the
 * File interface.
 *
 * @see Path
 * @see File
 * @see Paths
 * 
 * @author Eli Doran <eli@elidoran.com>
 *
 * @since 1.0
 */
public interface Folder extends Path
{

    /**
     * Creates the entire path through to this folder if it isn't already.
     *
     * @return true if it successfully created the path or if it exists.
     *
     * @since 1.0
     */
    public boolean create();


    /**
     * Returns a path to the named file/folder in this folder.
     *
     * @return The Path.
     *
     * @since 1.0
     */
    public Path getPath(CharSequence name);

    /**
     * Returns paths to all contents of this folder.
     *
     * @return The Path[].
     *
     * @since 1.0
     */
    public List<Path> getPaths();

    /**
     * Returns paths to the folder's contents with names that match the given regular expression.
     *
     * @param pattern The Regular Expression to match the file paths.
     *
     * @return The Path[].
     *
     * @since 1.0
     */
    public List<Path> getPaths(CharSequence pattern);

    /**
     * Returns the paths that match the given {@link Pattern}.
     *
     * @param pattern The Regular Expression Pattern to match the file paths.
     *
     * @return The Path[].
     *
     * @since 1.0
     */
    public List<Path> getPaths(Pattern pattern);


    /**
     * Returns a file in the folder.
     *
     * @param name The name of the file.
     *
     * @return The File.
     *
     * @since 1.0
     */
    public File getFile(CharSequence name);

    /**
     * Returns all the files contained by this folder..
     *
     * @return The List<File>.
     *
     * @since 1.0
     */
    public List<File> getFiles();

    /**
     * Returns the folder's files with names that match the given regular expression.
     *
     * @param pattern The regular expression to match the names to.
     *
     * @return The List<File>.
     *
     * @since 1.0
     */
    public List<File> getFiles(CharSequence pattern);

    /**
     * Returns the folder's files with names that match the given {@link Pattern}.
     *
     * @param pattern The Pattern to match the names to.
     *
     * @return The List<File>.
     *
     * @since 1.0
     */
    public List<File> getFiles(Pattern pattern);


    /**
     * Returns the folder's files with names that end with the given extension.
     *
     * @param extension The extension to test for at the end of the file name.
     *
     * @return The List<File>.
     *
     * @since 1.0
     */
    public List<File> getFilesWithExtension(String extension);


    /**
     * Returns the folder's files with names that end with any one of the given extensions.
     *
     * @param extensions The extensions to test for at the end of the file name.
     *
     * @return The List<File>.
     *
     * @since 1.0
     */
    public List<File> getFilesWithExtensions(String ... extensions);

    /**
     * Returns a Folder relative to this one by appending the given path to the file's path.
     *
     * @param path The path to the folder contained by this folder.
     *
     * @return The Folder.
     *
     * @since 1.0
     */
    public Folder getFolder(CharSequence path);

    /**
     * Returns the folders contained by this folder.
     *
     * @return The Folder[].
     *
     * @since 1.0
     */
    public List<Folder> getFolders();

    /**
     * Returns the folders that match the given regular expression.
     *
     * @param pattern The regular expression to match the names to.
     *
     * @return The Folder[].
     *
     * @since 1.0
     */
    public List<Folder> getFolders(CharSequence pattern);

    /**
     * Returns the folders that match the given {@link Pattern}.
     *
     * @param pattern The Pattern to match the names to.
     *
     * @return The Folder[].
     *
     * @since 1.0
     */
    public List<Folder> getFolders(Pattern pattern);


    /**
     * Processes this folders contents deleting all files and folders until it is empty and can be
     * deleted itself.
     * 
     * @return true only if folder and all contents are deleted.
     */
    public boolean deleteRecursively();


    /**
     * Searches, recursively, into folder for files with specified extension.
     * 
     * @param extension The desired extension files should have.
     * @return List<File> containing files with names ending with specified extension.
     */
    public List<File> scanForFilesWithExtension(String extension);


    /**
     * Searches, recursively, into folder for files accepted by FileFilter.
     * 
     * @param filter The filter to determine if a file is acceptable.
     * @return List<File> containing files accepted by filter.
     */
    public List<File> scanForFiles(FileFilter filter);

    /**
     * Searches, recursively, into folder for files accepted by FilenameFilter.
     * 
     * @param filter The filter to determine if a file is acceptable.
     * @return List<File> containing files accepted by filter.
     */
    public List<File> scanForFiles(FilenameFilter filter);


    /**
     * Gathers files from folder accepted by specified FilenameFilter.
     * 
     * @param filter The filter to determine acceptable files.
     * @return List<File> containing files accepted by filter.
     */
    public List<File> getFiles(FilenameFilter filter);

    /**
     * Gathers files from folder accepted by specified FileFilter.
     * 
     * @param filter The filter to determine acceptable files.
     * @return List<File> containing files accepted by filter.
     */
    public List<File> getFiles(FileFilter filter);


    /**
     * Returns the path from the specified parent folder to the folder represented by this Folder object.
     * 
     * @param parent The parent folder to start the path from.
     * @return The path to this folder object, or, null if NOT a child of specified parent folder.
     */
    public CharSequence getPathFrom(Folder parent);

}


/*
 * Copyright 2010 Eli Doran
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
